home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / c / pmm / doku / thirdpartytools / genproto.readme2 < prev    next >
Text File  |  1999-06-14  |  10KB  |  252 lines
  1.  
  2.                 GenProto v1.2
  3.  
  4.         Copyright 11 November 1996 by Nicolas Pomarède
  5.             pomarede@isty-info.uvsq.fr
  6.  
  7.  
  8.  
  9. Introduction
  10. ------------
  11.  
  12. This little tool was developped to scan C/C++ source files and to print
  13. the name of all the functions' definition.
  14. Definitions can then be sorted depending on various criterias, and results
  15. are printed to STDOUT or any other file.
  16.  
  17. The purpose of this tool is to automatically generate indexes of all
  18. the functions used in a project, which is very useful when you have to manage
  19. more than 10 or 20 files.
  20. You then have a kind of "table of content" which can help you to browse
  21. your sources more quickly when looking for a specific function.
  22.  
  23.  
  24.  
  25. Distribution and Disclaimer
  26. ---------------------------
  27.  
  28. This program is free, you can distribute it to anyone, as long as it
  29. remains free ; that is, you shouldn't charge more than the cost of the
  30. media used to distribute it.
  31. Also, you're only allowed to distribute the whole package, without
  32. removing any of the original files.
  33. Since the source are included, you can modify them. However, I would prefer
  34. you send me any modification before releasing the new source.
  35.  
  36. Although this program has been carefully checked, I take no responsability
  37. for any damage or loss of datas this program could cause.
  38. USE IT AT YOUR OWN RISK, and don't forget to read the "Limitations" part.
  39.  
  40. The following files are included:
  41.  
  42. README                This file
  43. genproto            Binary exe for 68000 Amiga
  44. genproto.readme            Small readme
  45. lex.yy.c            The file generated by lex (if you don't have lex)
  46. main.c                The main program
  47. makefile            Makefile for UNIX
  48. proto.h                Header for main.c / proto.l
  49. proto.l                The Lex definitions file
  50. smakefile            Makefile for SAS C on Amiga.
  51.  
  52.  
  53. GenProto latest version should always be available from the Aminet sites,
  54. whose main site is ftp.wustl.edu, in /pub/aminet/dev/c (packed with Lha).
  55. Look in /pub/aminet for the list of all the mirrors worldwide.
  56.  
  57.  
  58.  
  59. Usage
  60. -----
  61.  
  62. GenProto is a little tool to extract all the functions' definition contained
  63. in several C/C++ source files. GenProto will add the line number and the
  64. file name. You can then print the result with a customized printf which allows
  65. normal escape sequences, as well as %-command to print the special fields
  66. generated by genproto.
  67. The resulting output is very useful to improve the documentation of your program.
  68.  
  69.  
  70. The syntax of genproto is the following:
  71.  
  72. genproto [-h] [-d ] [-b] [-f<Format String>] [-s[CNFL]] [-o<Output File>] <Source Files>
  73.  
  74.   -h prints a little help
  75.   -d turns debug mode ON and prints all tokens
  76.   -b turns banner off (the little copyright text)
  77.   -f specifies the string used to print the functions. The default is:
  78.     "%R\t%C %S %N\t%P\tline %L, file %F\n"
  79.      Here's the meaning of the %-commands
  80.         %R : prints the return parameters of the function
  81.         %C : prints the ClassName of the function (if it exists)
  82.         %S : prints "::" if the ClassName exists
  83.         %N : prints the name of the function
  84.         %P : prints the input parameters of the function
  85.         %L : prints the line number of the function
  86.         %F : prints the file where the function is declared
  87.      Any other %-command will cause the program to stop.
  88.      All the \x escape sequences are recognized (\n,\t,...) except the octal
  89.      and hexadecimal conversion (\ooo and \xhh) (They must be preprocessed by your shell).
  90.   -s specifies the sorting criterias. The default is "CNFL", where C is the ClassName,
  91.      N is the FunctionName, F is the FileName and L is the LineNumber.
  92.      Functions will be sorted using the Sort String before being printed
  93.      (you can specify any number of criterias (up to 4)).
  94.   -o Results will be printed to Output File ; the default is stdout.
  95.  
  96. All others parameters are interpreted as files to be scanned (you can scan as many files
  97. as you want in one run).
  98.  
  99.  
  100. For example, if you type : "genproto main.c", you will get :
  101.  
  102. GenProto v1.2 (11/11/96) by Nicolas PomarÉde
  103.  
  104. void      Usage ( char *name )  line 133, file main.c
  105. char *    CharCopy      ( char *buf , int len ) line 174, file main.c
  106. char *    AddTokens     ( char **TokenList , int FirstToken , int LastToken )   line 191, file main.c
  107. void      AddPrototype  ( char **TokenList , int ClassNamePos , int FunctionNamePos , int ParamPos )  line 236, file main.c
  108. void      ScanOneFile   ( void )        line 300, file main.c
  109. void      SortPrototypes        ( struct function **T , int Gauche , int Droite )    line 403, file main.c
  110. void      Swap  ( struct function **T , int i , int j ) line 427, file main.c
  111. int       CompareFunctions      ( struct function *pF1 , struct function *pF2 ) line 452, file main.c
  112. void      CopyListToTable       ( void )        line 496, file main.c
  113. void      PrintOnePrototype     ( struct function *pF ) line 545, file main.c
  114. void      PrintPrototypes       ( void )        line 593, file main.c
  115. void      DeletePrototypes      ( void )        line 614, file main.c
  116. void      MyExit        ( void )        line 649, file main.c
  117. void *    MyAlloc       ( size_t size ) line 663, file main.c
  118. void      main  ( int argc , char **argv )      line 687, file main.c
  119.  
  120.  
  121. GenProto can also cope with C++ files and recognizes the "::", "~" and ":" in
  122. functions' definition. Due to the more complex grammar of C++ and to the
  123. simple implementation I use, this might not work properly in all the cases
  124. (although I tested it on many C++ files without any errors).
  125.  
  126.  
  127. Internal work / Technical infos
  128. -------------------------------
  129.  
  130. The lowest level of this program is a LEX scanner that reads "words"
  131. from the source files. These words are called "tokens" and have different
  132. values, depending on their role in a function's definition.
  133.  
  134. They are 6 kinds of tokens:
  135.   RESET        This value is returned if the associated token can't appear
  136.         in a function's definition (e.g. for, if, while, auto, ...)
  137.         The tokens' stack is then emptied (see later).
  138.   KEYWORD    This value is returned if the associated token is a C/C++
  139.         instruction that can appear in a definition.
  140.   ID        This value is returned for any tokens made of the letters
  141.         '~', '_', 'A'..'Z', 'a'..'z' and '0'..'9', but not
  142.         belonging to the C/C++ list of reserved words.
  143.   PARAMS    This value is returned when a bloc delimited by an opening
  144.         '(' and a closing ')' has been found. Such a bloc might
  145.         contain embedded pairs of '(' and ')'.
  146.   BLOC        This value is returned when a bloc delimited by '{' and '}'
  147.         is found. In such a case, all the data inside this bloc
  148.         are ignored (since such a bloc can't contain function's
  149.         definition).
  150.   DEUX_POINTS    Returned if the string "::" is encountered ; this only
  151.         happens in C++ files and is used to separate the class
  152.         name and the function's name.
  153.  
  154. Each time LEX returns a token, it is stored in a stack, depending of its
  155. value and of the previous state of the stack.
  156. If a token doesn't appear in the right order to define a function, or
  157. if the RESET value is returned, the stack is emptied and eveything restarts
  158. from the current location.
  159.  
  160. Tokens are stacked as long as a valid tokens combination has not been found
  161. (that is, as long as we haven't reach the end of the function's definition).
  162.  
  163. A valid stack could be created by:
  164.  
  165. int    main (int argc , char **argv)
  166. {
  167.  ... some code ...
  168. }
  169.  
  170. resulting in:
  171.     KEYWORD        int
  172.     ID        main
  173.     PARAMS        (int argc , char **argv)
  174.     BLOC        { ... }
  175.  
  176. After stacking a BLOC over a PARAMS, we know we encountered a function's
  177. definition (use the "-d" option if you want to see the stack).
  178.  
  179. The tokens of the stack are then stored in a 'struct function' with the
  180. following members:
  181.  
  182.   char            *ReturnParam;    ->    "int"
  183.   char            *ClassName;    ->    EmptyString
  184.   char            *FunctionName;    ->    "main"
  185.   char            *Param;        ->    "(int argc , char **argv)"
  186.   int            Line;        ->    nnn
  187.   char            *File;        ->    "somefile.c"
  188.  
  189.  
  190. All these 'struct function' are then stored in a linked list, which
  191. is further sorted using the specified criterias in their order of
  192. appearance (we use a "quick sort" algo). Do apply the quick sort,
  193. the list is first converted into a single array.
  194.  
  195. The resulting (sorted) array is then printed according to the Format String.
  196.  
  197.  
  198.  
  199. Limitations
  200. -----------
  201.  
  202. This program has been mainly made for C source file ; I then added
  203. support for C++, but due to the more complex grammar, I'm not sure
  204. it always works right. Please, report any bug.
  205.  
  206. Some of the variable have fixed length at compilation time. Although
  207. I chose some rather large numbers, you should note the following :
  208.  
  209.  - You have 4 sorting criterias, this means the parameter of the "-s"
  210.    option should't have to exceed 4 characters. Just in case, the
  211.    internal buffer is 10 byte long.
  212.  
  213.  - When using the "-f" option, the format string is copied into
  214.    a 1000 byte long buffer. Don't use format string longer than
  215.    1000 bytes (this should be largely enough in all the cases), all
  216.    exceeding chars will be ignored.
  217.  
  218.  - The parameters of a function's definition shouldn't exceed 2000 bytes;
  219.    Any exceeding character will be suppressed (2000 bytes is more than
  220.    20 lines; who uses more than 20 full lines of parameters ?
  221.    (nobody I hope :) ).
  222.  
  223.  - A function definition should not include more than 50 tokens
  224.    (all the parameters of the function are considered as ONE token).
  225.    If such a case should appear, the function would be ignored.
  226.  
  227.  
  228. Also, as a last remark, I would recommend to apply genproto on files
  229. that compile without errors, and only on C/C++ files.
  230.  
  231.  
  232.  
  233. Future
  234. ------
  235.  
  236. This tool has been written in a few days, only to quickly create an index
  237. of all the functions I used in a rather big C++ project.
  238. If you find any bug or have ideas of improvement, don't hesitate to contact me.
  239. I will try to do it as soon as possible, but I'm doing my military service :(
  240.  
  241.  
  242.  
  243. Contact Adress:
  244. ---------------
  245.  
  246. Nicolas Pomarede
  247. 13 allee des Vignes
  248. 78120 Rambouillet
  249. France
  250.  
  251. e-mail: pomarede@isty-info.uvsq.fr
  252.